Aminet 3

home *** CD-ROM | disk | FTP | other *** search

/ Aminet 3 / Aminet 3 - July 1994.iso / Aminet / util / cli / ADoc2_v400.lha / ADoc / ADocEnglish.doc < prev next >

Wrap

Text File | 1994-05-14 | 25.4 KB | 576 lines

ADoc - User's Manual AboutThisDoc This manual describes release 4.00 of the utility ADoc. This program is (c)1990-1994 by Denis GOUNELLE, any commercial usage or selling without author's written authorization is strictly forbidden. You can copy and spread this program under the following conditions: - all the files are provided - the files are not modified in any way - you don't charge more than $6 for copy fee In spite of several tests, no warranty is made that there are no errors in ADoc. YOU USE THIS PROGRAM AT YOUR OWN RISK. In no event will I be liable for any damage, direct or indirect, resulting of the use of ADoc. AREXX is (c)1987 by William Hawes. PowerPacker 2.3b is (c)1989 by PowerPeak and Nico FRANCOIS PowerPacker Pro 3.0b is (c)1990 by PowerPeak and UGA Software The "powerpacker.library" library is (c)1990 by Nico FRANCOIS The "reqtools.library" library is (c)1990 by Nico FRANCOIS >>> CLOSE THIS WINDOW TO CONTINUE <<< Foreword ADoc2 is a new release of ADoc, fully rewritten in order to remove some limitations and add several improvements. Note some incompatibilities arose particularly at argument level. This program works equally under 1.3 and 2.0 system releases. ADoc is an utility that allows you to manage all kinds of documentations on any subject. It is able to automatically start searching for a word selected by a mouse click, and to work on several documentation files at the same time. ADoc can also use straight the AutoDocs and AmigaGuide files, as well as "PowerPacker" compressed files. Criticisms and suggestions will always be welcomed. Write to: M. GOUNELLE Denis 27, rue Jules GUESDE 45400 FLEURY-LES-AUBRAIS FRANCE You can also send a message to the following Internet address : "gounelle@alphanet.ch". Note that this mailbox is not mine, so please send only short messages. As I don't have direct access to the messages, don't expect an answer before a dozen of days. Thanks to Jean-Yves PROUX and Helmut J. ESENWEIN for their numerous suggestions, to Reza ELGHAZI for his help concerning AmigaGuide files, and to Simon HEWINSON who translated in English the "amiga.doc" file. Special thanks to Jean-Philippe RAPP for his ideas and his help concerning AutoDocs files. Installation ADoc needs "reqtools.library" (version 2.0c or higher) to run. You must copy this file in your "LIBS:" directory, if not yet done. ADoc is now localized, so it can adapt itself to your favorite language. All you have to do is to copy the good catalog file into the directory corresponding to your language. For exemple, if your default language is french, copy the "français.catalog" into the "SYS:Locale/Catalogs/Français" directory, under the name "ADoc.catalog." The german catalog was translated by Stefan SALEWSKI. HowDoesItWork ADoc works on documentation files, combined with a keyword (this one is named "term" in this doc). Every doc file has an index file that allows to access the wanted terms nearly immediately. (Note : as a result, each time you change a doc file, you'll have to rebuild its index file.) When ADoc is running, only is loaded in memory the index file. The name of this index file will be the doc file name plus an ".index" suffix. You can create your doc files with your favourite text editor; these files consist of a series of definitions and each definition has a syntax as follows : term text line 1 text line 2 etc... text line n At first, consider that the first two lines of a doc file have to be empty (or in extreme circumstancies begin with a space or a tab character). The first character of each term must be at column 1 and the text lines must begin with a space or a tab character. Empty lines are allowed. One term can't be more than 32 character long and can't contain any blanks or tabs : valid characters are upper or lower letters, digits, underline, and accented letters (ASCII codes between 217 and 246). However, if needed, you can extend this character set (see below AdvancedConcepts). The term amount for each file as well as the text line amount for each term are unlimited (or rather, this limit is so large that you'll be short in memory long before). A text line can't be more than 256 characters. In order to bring out some parts of your text, you can use the following ANSI sequences : ESC[1m boldface on ESC[3m italics on ESC[4m underline on ESC[22m boldface off ESC[23m italics off ESC[24m underline off ESC[0m normal character set RunningADocfromCLI ADoc can be run from Workbench or from the CLI. By default, the doc file is "Amiga.doc", but, of course, in both cases, you can specify another filename. From the CLI, you can specify the following arguments : WBENCH Asks ADoc to use the Workbench screen. When this argument is missed out, ADoc will open its own screen sized as the Workbench screen. On error, when opening screen, ADoc will go automatically to the Workbench screen. LACE Asks ADoc to use an interlaced screen. If you asked to use the Workbench screen, and this one is not in interlaced mode, this argument will be ignored. DEPTH n Asks ADoc to use a n-planes screen (allowing 2^n colors). If you asked to use the Workbench screen, this argument will be ignored. FONT name Asks ADoc to use a given font rather than the default one. Name must take the form <FontName><SizeY>, for ex. "topaz8". ADoc is able to use any non proportional font so long as its size is 8 at least. If ADoc can't open the requested font, it will attempt to use the default one. If this font doesn't suit or ADoc can't open it, it will try to access the topaz8 font. If it fails, ADoc will end immediately. MAKEIDX Tells ADoc the only operation to do is to create the index files. QUICK Asks ADoc not to display a text combined to the "AboutThisDoc" term, when starting. Usually, each time ADoc opens a file, it looks for the "AboutThisDoc" term in this file, and then, if this one exists, displays the corresponding text and waits for user to close the window before continuing. AREXX Asks ADoc to go in AREXX mode. More information on how to use ADoc with AREXX in TheAREXXMode section below. ONEWINDOW Asks ADoc to open only one window at a time. NOCASE Asks ADoc not to differentiate lower and upper characters when processing files. This only will concern files whose name is given after this option. NOSORT Asks ADoc not to sort the indexes of files whose name is specified after this option. TABSIZE n Tells the tab size for the files whose name is specified after this option. Default size is 8. Any other argument will be considered as a doc file name to be used. You can specify several files, by separating their names by spaces or commas (for ex. "ADoc file1 file2" or "ADoc file1,file2"). You can mix file names and options but let us remember that NOCASE, NOSORT, and TABSIZE options only concern files you specified after these options. ADoc will open these files in this given order. Unless you indicate one full path, firstly files will be looked for in the current directory, then in the "ADOC:" one. If you specify a directory name instead of file name, ADoc will open all the files in this directory (apart from ".info" and ".index" files). RunningADocFromWorkbench From Workbench, you can inwoke ADoc in several ways : - by double-clicking on its icon (then ADoc will use the default documentation file) - by double-clicking on one file icon having ADoc as default tool (field "DEFAULT TOOL") - by clicking on icons of several files, holding down the SHIFT key, and double-clicking on the ADoc icon. In all these cases, ADoc starts by looking into "TOOL TYPES" field of the program icon; this one may contain : FONT=name DEPTH=n OPTIONS=[WBENCH][LACE][MAKEIDX][QUICK][AREXX][ONEWINDOW] For more information on these options, see the RunningADocfromCLI section. Note option names must be separated by a "|" sign. After that, ADoc will open the doc files you specified; it will open them as it does from CLI except it examines the "TOOL TYPES" field of each icon. This field may contain : TABSIZE=n OPTIONS=[NOCASE][NOSORT] For more information about these options, see the RunningADocfromCLI section. Note these three options only will concern the file corresponding to the icon. StartingADoc As I explained above, ADoc starts by opening some specified file(s). At this time, ADoc attempts as well to open the index file corresponding to each doc file. If you didn't specified any file to open, ADoc will look if the "ADocFile" variable is defined : if so, it's value is used as a file name. Otherwise, the default file name is "Amiga.doc". You can specify several file names is the "ADocFile" variable, just as from command line (for example: setenv ADocFile "exec.doc dos.doc"). If ADoc can't find the index file, it will offer to create it. If you refuse, this doc file will not be usable but, in spite of it, ADoc will attempt opening other files. If ADoc detects a doc file was changed after an index was created, it will offer to update the index file. If you refuse, in spite of it, the doc file will be opened but later ADoc will be able to detect errors if the file contents was changed. Note the date of index file creation is stored in the index file itself. Once all files are opened, ADoc will display a requester; this one indicates the term list of first open file. We'll describe how to use this requester in the TheTermRequester section. TheTermRequester A term can be pointed out by a mouse click on it. Now this term is displayed in a different colour. If you click a second time on it, the requester is switched off and ADoc displays in a window the text corresponding to that term. I'll describe how to use these windows in HowToManageWindows section. To choose a term, you can use the keyboard too. If you press any key, the key letter will be added to the current "prefix" (displayed in a rectangle below the term list), and ADoc will display the list starting from the first term that begins with this prefix. ADoc will complete this prefix as far as possible. If you press the <BACKSPACE> key (above the <RETURN> key), the last prefix character will be deleted and the list will be updated too. If you press the <RETURN> key, ADoc will display the text corresponding to the first term that begins with this prefix. Note ADoc will not differentiate upper and lower letters when the current file is indicated after a NOCASE option. You can close the requester without selecting a term both by pressing the <ESC> key and by clicking in the close gadget either. If no window is open at this time, the program will abort. In fact, a term requester can allow you to select from among three lists : the term list of the current file, the list of the opened files (if you have several opened files) and the list of terms that ADoc found during the previous search operation (provided a search was made before, see the Search section below). At the bottom, on the right corner of term requester, you have a letter showing what a list is displayed : term list (T), file list (F), list of found terms (S). To pass from a list to another, click the right mouse button holding down one of the <SHIFT> keys, or press the <TAB> key. When the file list is displayed and you select a file in this list, ADoc returns automatically to the term list and displays the list of terms in that file. When no window is open, the term requester has a menu with the following options : Open window see TheSpecialMenu below Search see the Search section below Iconify see the TheProjectMenu below Quit this one allows to quit ADoc. HowToManageWindows When you select a term, ADoc opens a window to display the corresponding text. When a term is defined several times either in a single file or in several different files, all text lines will be joined in a queue and displayed in one window. The window height is dependent on the amount of lines ADoc must display. If there are too many lines, only the first page will be displayed and ADoc will add two arrow gadgets (on the right top corner) for scrolling this text. Of course, you can have several windows opened at the same time. In this case, the window which was activated when opening a new window is called the "parent window" of the new one. By default, these windows have standard close, dragging, back and front, and sizing gadgets. If you change the size of a window, ADoc, if needed, will add or remove automatically the arrow gadgets. Each window has three menus too : there are "Project", "Tools" and "Special" menus (I'll describe these ones in TheProjectMenu, TheToolsMenu and TheSpecialMenu sections, below). Finally, note ADoc recognize the following keys : HELP list keys and their meaning ESC close the current window UP previous page DOWN next page BACKSPACE open parent window Shift-UP previous term Shift-DOWN next term When you click on a word, this one will be displayed in a different colour. If you click again on the same word, ADoc will automatically start searching for the corresponding term in all open files. If this fails, screen flashes, otherwise a new window will be brought up. TheProjectMenu Other term Bring up the term requester (see above TheTermRequester). Print Print the text contained in the active window. Note : the possible ANSI sequences will be correctly interpreted by the printer. Iconify Leave ADoc sleeping : if ADoc opened its own screen, this one will be closed, all the windows will be switched off and then ADoc will open a small window on the left top corner in the Workbench's screen. If you click on the close gadget of this window, ADoc will ask you to confirm it before you abort. For "awaking" ADoc, activate this window and click the right mouse button. Normally, ADoc keeps in memory all the text lines to be able switching on quickly all the windows when it would be awaken. The one drawback is that all possible memory will not be freed, so, when you ask ADoc to iconify itself, ADoc will ask you if you want to close all windows. If you say yes, the memory will be completely freed and when ADoc will be awaken, it will bring up the term requester. Help... Displays some useful keys and their meaning (same as pressing the HELP key) About... Display some infos about ADoc. Click inside this window or press a key to continue. Quit Allow to quit ADoc (asks you to confirm it). TheToolsMenu Front Screen Allow to use ADoc in a already open screen (for ex. that one of your text editor). Only you need to move the screen -where you want switch on ADoc- in front of any screen, drag it down to unfold the screen where ADoc is. Now, select this item : ADoc will close all the open windows and reopen these ones in the foreground screen. CAUTION: Of course, you'll have a "Guru" if the screen where you placed ADoc is closed before you quitted ADoc (or placed this one on another screen). Note this command will not work if you did not specify a font (see above the RunningADocfromCLI section) and the font of your front screen doesn't suit. Close all Allow to close all the windows at the same time. After it asked you to confirm, ADoc will close every window and display the term requester. Find Allow to start searching (see the Search section below). Information Display the account of avalaible files and terms, just as the account of opened windows and displayed lines. To continue click on the "Ok" gadget. TheSpecialMenu Open file Allow to open an additional doc file. A file requester is brought up so that you can specify what a file must be opened. Close file Allow to close the current file (i.e. the file where is defined the term displayed in the active window). After it asked you to confirm, ADoc will close all the windows relied to this file and will close it. Note this command will work only if at least two files are opened. One window If this option is selected, ADoc will open only one window at a time. Search In the text lines, ADoc has the capability to search up to four strings simultaneously and display then the list of the relied terms. When you select the "Search" item in the "Tools" menu, a window is switched on with four string gadgets. You have also an "CANCEL" gadget, to abort this operation, a "OK" gadget, to start your search, and an "Options" menu : low = UPP Ask ADoc not to differentiate upper and lower letters when searching. All strings Normally, ADoc is looking for all terms containing one of the strings you introduced. On the contrary, this item allows you to search for terms contaning ALL strings you specified. All files Ask ADoc to search in all open files, not only in the current file. When you start your search, a requester appears. The "Stop" gadget allows you to break this search. As soon as the search finished, screen will flash if no term was found. Otherwise, the term requester will be switched on and will display a list of found terms. That list is sorted, and kept in memory until you stard a new search. AdvancedConcepts Since v4.00, you can associate an IFF picture to a term. This picture will be loaded at the same time as the text, and will be displayed in the same window. In order to use this fonctionnality, you just have to add a special line in the term's text : . adoc@<position> <picture's name> where <position> is "top", "bottom", "left" or "right". The picture will be displayed in the given border. For example, if you enter : . adoc@right doc:exec/schema1.pic the picture "doc:exec/shema1.pic" will be displayed next to the right border of the window. ADoc is able to load pictures in a different screenmode and/or colors numbers than the current screen. The screen's palette will be modified with the picture's palette. The release 1.40 of ADoc introduced the concept of aliases, that is a manner to associate a same text to several terms, without having to repeat the text several times. An alias definition follow the syntax: name1 alias name2 The first character of "name2" must, as for any term definition, be at column one. There must be at least one space or tabulation between the three words. The word "alias" must be in lower case characters. The effect of such a definition is that when the user will ask to get the "name1" term, ADoc will automatically display the "name2" term instead. Aliases appear in the term requester, and in the search function. You must be aware that there is *NO* recursivity check between aliases ! An application of aliases could be the documentation of a function library : often you will define several functions together. With the aliases, you can allow access to the definition by the name of each function, but the text is defined only once. ADoc can combine automatically several doc files. For that, it's enough to specify the name of file(s) to be combined, in the first line of file which you want associate them with. If this line is empty or begins with a space or tab, its contents will be ignored. File names have to be separated by spaces or commas. You can indicate a directory name; in this case all the files of that directory will be opened (except ".info" and ".index" files). To extend the character set you can use in a term, it's enough to specify additional characters in the second line of your doc file. If this line is empty or begins with a space or tab, its contents will be ignored. Otherwise, all characters of that line (up to first space, tab, slash or form feed) will be added to the default character set. Note this character set extension only will concern that file. ADoc has the possibility to load directly any compressed "PowerPacker" file, providing you have set up "powerpacker.library" in your LIBS: directory. It's not necessary (but recommended) to create the index file before you compress a doc file. ADoc will refuse to load an encrypted file. After ADoc has decompressed a file, this will be copied in a temporary file in the "T:" directory. So, using compressed files can arise some memory problems, especially if you put T: directory in your RAM: disk. This temporary file will be deleted when you close it. TheAREXXMode ADoc always opens a compatible AREXX port, named "ADoc_rexx". Messages on this port are waited for at the same time as Intuition messages on text windows, and can take the following forms : QUIT quit ADoc REQUEST bring up the term requester FSCREEN ADoc moves all it's windows to the front screen TOFRONT put ADoc screen in front of all screens TOBACK put ADoc screen in back of all screens FIND term start searching for a given term, and display the corresponding text if it is found OPEN file allows to open a other file while running ADoc The return code (RC variable) will be set to zero, except in the following cases: bad request (return code 20), "OPEN term" request with "term" not found (return code 5), "request" request and no term choosen (return code 5). Here is an example asking for help for the term "alias" : /* Ask for help for "alias" */ ADDRESS "ADoc_rexx" "FIND alias" IF RC = 5 THEN SAY "not found !" Note quotes surrounding commands ! If you launch ADoc with the option AREXX, the program operation will be quite different : once ADoc opened the doc file(s), it will not switch on the term requester but will display a message "Waiting for an AREXX message" and will wait for messages on the AREXX port (or for CTRL-C to abort it). Moreover, when the last window will be closed, the program will not end itself but go back waiting for AREXX messages. AutoDoc_files_support ADoc can recognize and use the AutoDocs files from Commodore. In most cases, no change are needed, but it is recommended to verify their format: you must have at least two empty lines at the beginning, followed by the table of contents and every term must start at column 1. In some cases, you won't find empty lines at the beginning, and terms will begin at column 2 and will be preceded by a "form feed" character (i.e. CTRL-L). The program "AutoConvert", distributed with ADoc, will allow you to convert those files into a correct format (Note : this program can only be used from CLI). In all other cases, you'll have to convert these files by yourself. AmigaGuide_files_support ADoc can now recognize AmigaGuide files, build their index files, and display their contents. The different syntaxes of the "@node" directive are handled : @node name @node "title" @node name "title" In the latter case, an "name" alias is automatically defined for the "title" term. The "@title" directive is also handled. As ADoc doesn't handle spaces in term names, they are replaced by underscore characters. Links within text are displayed in boldface. As names are truncated to 32 characters, some links may fail. Note that ADoc handles inter-files links, like: @{"foo" link help:general/bar} To allow such links, delimiters are automatically set to ":/." for AmigaGuide files. TheADocMessages When an error occurs, ADoc displays in a small window a name (usually, a filename) and an error code. This one is either an AmigaDOS error code or an internal code. In the first case, see your AmigaDOS Manual (or use the command "Fault") to have more information on this error code. There are the internal error codes : -1 empty file -2 read error -3 file is wrong (bad format, etc...) -4 file is compressed and there is no "powerpacker.library" -5 a problem occured while decrunching -6 bad picture specification -7 error while loading picture